Release 10.1A: OpenEdge Development:
Progress Dynamics Basic Development

Defining items

An Item can be a menu item in a menu, or a tool in a toolbar, or it can be both. It is a visual representation used to perform an action within the application. The item can publish an event, run a procedure, or launch another application window. When in a toolbar, the item can be visualized as a button, label, or separator. Items can be reused in multiple bands.

To create a new item, do one of the following:

Right-click on the Category where the item is to go, and select Add Item. Figure 12–6 shows you all the data that can be entered for an item. The First button for the Navigation category is used as an example.
Select any existing item and then choose the Add button in the update panel in the Item Maintenance tab on the right.



Figure 12–6: Toolbar and Menu Designer—Item tab folder

The Item Type can be one of the following:

Action — Specifies that this is a user action that appears on a menu or toolbar. When on a toolbar, the item is visualized as a button. When on a menu, the item is visualized as a menu item.
Label — (for menus only) Indicates this item will be used strictly as a submenu item. That is, it defines a label to be used to identify a submenu defined separately.
Placeholder — Used as a placeholder for dynamic menus or toolbar bands. Each individual container where the toolbar object is used can define its own band of items to be inserted in the spot reserved by the placeholder. (See the "Band object associations" section for more information on how this is defined.)
Separator — Can be specified when the action is on either a toolbar or a menu. When on a menu, a rule (a separating line between items) is created. When in a toolbar band, a line appears separating the buttons. This type of item cannot be added to a top-level (MenuBar) menu structure.

Rules

Rules are used to enable/disable items, hide/view items, or swap images in toolbar buttons. A rule contains a delimited list of either function references or properties that specify a logical result (either Yes or No), as shown:

Syntax: [ property | function ] = list [ AND | OR ] ...

property

The name of a property whose value is retrieved across the specified Item link. This can be any SmartObject property defined in the object across the Item link.

function

A function that is executed across the specified Item link.

list

A comma-delimited list of values that is compared to the property or function result. An OR comparison is performed.

You can define rules to change the state of items in the following ways:

Enable Rule — Defines whether the item is enabled.
Hide Rule — Defines whether the item will be hidden or viewed. A logical YES result hides the image. A NO result displays the image.
Alternate Image Rule — If there is an alternate image defined (Image 2), this defines the criteria to show either Image1 or Image 2. A TRUE result swaps the image with Image 2. A FALSE result swaps the image with Image 1.

Here is an example from the Enable Rule for the First navigation button:

QueryPosition=LastRecord,NotFirstOrlast and canNavigate()

QueryPosition is an SDO property that keeps track of whether the SDO’s query is positioned at the beginning, the end, or somewhere else in the data set. The expression “QueryPosition=LastRecord,NotFirstOrlast” means “IF QueryPosition = LastRecord or QueryPosition = NotFirstOrLast”. In other words, if the SDO query is positioned on the LastRecord or positioned somewhere in the middle, then it is appropriate to enable the First button to allow the query to be repositioned to the beginning.

The canNavigate function is defined for SDOs also (in the super procedure data.p, among other places). It returns true if there are no dependent uncommitted updates pending that need to be committed before the query can be repositioned. If both the QueryPosition and canNavigate conditions are met, then the First item (menu item or toolbar button) is enabled. Similar rules are defined for the other navigation items (Next, Prev, and Last).

Here is another example for the Save item in the TableIO Category, which groups buttons and menu items used in the update bands of toolbars:

NewRecord=add,copy or DataModified

The NewRecord SDO property is set to Add if a new record is being added. It is set to Copy if a new record is being created based on an existing record. Otherwise it is blank. The DataModified SDO property is TRUE if an existing record has been modified on the screen but not yet saved. If either of these conditions is met, then the Save item is enabled.

For more information on SmartObject properties and functions you can use to form rules for changing the state of your items, see OpenEdge Development: ADM Reference .

Note: If you create a rule using custom properties, remember to define the properties in the class. The class must also contain a get function to retrieve each new property.